Summary

Adds skill-memory — per-skill "motor memory" that gives a skill cross-session recall of its own hard-won lessons (gotchas, discoveries, fixes, workflow steps). When a skill's SKILL.md declares skill-memory: { enabled: true }, accumulated notes for that skill surface automatically in a <skill-memory> block appended to the skill tool's result on every load — and, with the historian extension, the historian writes those notes automatically during compaction (no agent action required).

It's fully opt-in per skill and cache-safe by construction: the block rides the tool-result tail (conversation), never the cached system/m[0] prefix, so it can't bust the prompt cache.

How it works

• Transparent recall — three-hook augmentation: tool.definition advertises an intent param; tool.execute.before stashes the intent (bounded TTL); the after-hook parses the skill's Base directory, reads its SKILL.md frontmatter, and formats the recall block. Lands in the tool RESULT (cache-safe).
• Write paths — ctx_skill_note (agent-authored) and the historian (auto-extracted). Both dedup on a normalized hash.
• Intent-scoped ranking — a recall cascade: model-matched embeddings → cosine blend over intent_embedding + delta_embedding (relevance/recency/hit weights tunable per skill via ranking_* frontmatter); FTS5 fallback over a content-linked skill_memory_fts vtable; flat recency×hit fallback.
• Historian auto-extraction — the historian sees TC: skill(<name>) markers in its chunk and emits a <skill_observations> block; both the OpenCode and Pi runners promote those post-commit as global notes (project_identity='*', source_type='historian'), recallable from any project.

Review units (4 commits)

The branch is organized into four coherent, reviewable phases:

1. P1 — transparent per-skill recall: skill_memory table migration, the three-hook augmentation, flat recall + storage, ctx_skill_note/ctx_skill_recall tools, opt-in distill-skill-memory dreamer task, TUI/ctx-status stats, docs.
2. P2 — embeddings + intent-scoped recall: delta_embedding + recall_count columns + skill_memory_fts FTS5 vtable; embed-on-write; the cosine/FTS recall cascade; a programmatic (no-LLM) reembed pre-step.
3. P3a — historian-extraction foundation: the TC: skill(<name>) marker keystone; origin_project + source_type columns; global-tier notes unified under project_identity='*' (collision-merge); partitionKey routing.
4. P3b — historian auto-extraction pipeline: prompt emits <skill_observations>, parser, validated-result threading, both runners promote via the shared promoteSkillObservations helper, plus an initializeDatabase self-heal net (re-creates skill_memory + ensureColumn so an upgraded DB recovers even if a migration row is lost).

Schema / migrations

Three migrations (numbered after the current master ceiling): skill_memory table, then delta_embedding/recall_count/FTS, then origin_project/source_type/* unification. LATEST_SUPPORTED_VERSION bumped in lockstep (the schema-version-fence test enforces it). Migration bodies are ensureColumn/IF NOT EXISTS idempotent.

Testing

Full plugin + Pi suites pass (one unrelated pre-existing full-suite ordering flake in tui-config.test.ts that passes in isolation), tsc clean both packages, lint clean, build produces all bundles. Dedicated coverage for the migrations (coexistence + fence), recall rungs, the tools, FTS triggers/backfill, the '*' collision-merge, and the historian promotion path on both runners. Verified working live: the historian auto-extraction writes genuine source_type='historian' notes, embeddings populate, and the read-side recall_count increments on surfacing.

Notes for reviewers

• Migration version numbers are placeholders relative to this fork's base — happy to renumber to whatever slots are free at merge time.
• The four commits are independently meaningful; if you'd prefer this as stacked PRs (P1 / P2 / historian), I can split it.

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

Summary by cubic

Adds per-skill cross-session memory: a cache-safe <skill-memory> block is appended to each skill tool RESULT with intent-scoped recall (embeddings + FTS) and historian auto-extraction into global notes. Ships the opt-in distill-skill-memory dreamer task, ctx_skill_note/ctx_skill_recall tools, TUI/CLI stats, and DB migrations to v52 with a self-heal path.

• New Features

  • Transparent per-skill recall: the skill tool optionally accepts intent; before-hook stashes it and after-hook injects recall; ctx_skill_note writes and ctx_skill_recall reads; Status/TUI show per-project totals and pinned counts.
  • Ranking + embeddings: cosine blend over intent_embedding + delta_embedding with FTS5 fallback; programmatic re-embed backfills NULL/stale vectors before distill-skill-memory.
  • Historian auto-extraction: TC: skill(<name>) markers → <skill_observations>; both runners promote via promoteSkillObservations as global '*' notes (source_type='historian').
  • Schema/migrations/self-heal: skill_memory table + FTS vtable/columns; LATEST_SUPPORTED_VERSION=52; initializeDatabase re-creates missing objects and rebuilds skill_memory_fts when needed; dashboard/CLI/config include the distill-skill-memory task (off by default).

• Bug Fixes

  • Cross-partition recall: union a skill’s partition with global '*' so project-local skills surface historian-written notes; writes/dedup remain exact-partition.
  • Frontmatter gating: reject ctx_skill_note when skill-memory.enabled is false or missing to prevent orphaned, unrecallable notes.
  • Disabled-path safety and routing: guard ctx_skill_note when the plugin is disabled; correctly classify singular ~/.config/opencode/skill/** as global; normalize Windows paths.
  • Frontmatter parsing: accept inline skill-memory: { enabled: true }; anchor to start-of-file; tolerate leading BOM/whitespace; strip inline # from unquoted scalars.
  • Historian marker + intent stash: emit TC: skill(<name>) verbatim (CR/LF/tab only are unsafe); key stashed intents by sessionID:callID and prune on session delete.
  • Prompt guidance + observability: drop ctx_memory cross-reference in skill guidance when memory is off; log recall errors; escape apostrophes in SQL.
  • Token budgeting + tier derivation: count per-note XML framing and clamp pinned budget; derive tier via dirname(resolvedPath) for robustness.

^{Written for commit 3a1733d. Summary will update on new commits.}

Confidence Score: 5/5

Safe to merge. All issues from the previous review are fixed; the remaining observations are minor naming/redundancy nits with no impact on correctness.

The three-hook recall injection, historian promotion, and migration self-heal are all correctly implemented. Previously reported bugs — cross-session intent eviction, orphaned project-local historian notes, ctx_skill_note writing to disabled skills, missing FTS rebuild in initializeDatabase — are all confirmed resolved. The two remaining observations (double recallPartitionPredicate call in searchSkillMemoryFts and the pre-partitioned key convention in the recall stack) are style/maintenance concerns with no effect on runtime behavior.

The storage.ts and recall.ts skill-memory files have minor code-quality observations but no correctness issues. The migration files and storage-db.ts self-heal are solid.

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Model
    participant SkillTool as skill tool (hook)
    participant HookHandlers
    participant Registry as skillLoadRegistry
    participant IntentStash as intentByCallId
    participant RecallCore as recallSkillMemoryBlock
    participant DB as SQLite (skill_memory)
    participant Historian

    Model->>SkillTool: skill(name, intent?)
    SkillTool->>IntentStash: stash intent keyed sessionID:callID
    SkillTool->>Model: skill output (Base directory line)
    HookHandlers->>HookHandlers: parse provenance from output
    HookHandlers->>HookHandlers: readFileSync SKILL.md → parseFrontmatterConfig
    HookHandlers->>Registry: "set sessionID:skillId → {tier, path, frontmatterConfig}"
    HookHandlers->>IntentStash: getAndDelete intent by sessionID:callID
    HookHandlers->>RecallCore: recallSkillMemoryBlock(skill, intent, scope, projectIdentity)
    RecallCore->>DB: embedTextForProject(intent) → vector
    alt embeddings available (rung 1)
        RecallCore->>DB: getRankingCandidates → cosine rank
    else FTS fallback (rung 3)
        RecallCore->>DB: searchSkillMemoryFts(sanitizedIntent)
    else flat fallback (rung 2/4)
        RecallCore->>DB: getSkillMemoryNotes ORDER BY recency x hit
    end
    RecallCore->>DB: bumpRecallCountByIds
    RecallCore->>HookHandlers: skill-memory XML block
    HookHandlers->>Model: append block to tool result

    Model->>DB: ctx_skill_note(skill, intent, kind, delta)
    DB->>DB: hash-dedup + cosine-dedup + insertSkillMemoryNote

    Historian->>DB: promoteSkillObservations(observations[])
    DB->>DB: "tier=global, project_identity=*, source_type=historian"

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Model
    participant SkillTool as skill tool (hook)
    participant HookHandlers
    participant Registry as skillLoadRegistry
    participant IntentStash as intentByCallId
    participant RecallCore as recallSkillMemoryBlock
    participant DB as SQLite (skill_memory)
    participant Historian

    Model->>SkillTool: skill(name, intent?)
    SkillTool->>IntentStash: stash intent keyed sessionID:callID
    SkillTool->>Model: skill output (Base directory line)
    HookHandlers->>HookHandlers: parse provenance from output
    HookHandlers->>HookHandlers: readFileSync SKILL.md → parseFrontmatterConfig
    HookHandlers->>Registry: "set sessionID:skillId → {tier, path, frontmatterConfig}"
    HookHandlers->>IntentStash: getAndDelete intent by sessionID:callID
    HookHandlers->>RecallCore: recallSkillMemoryBlock(skill, intent, scope, projectIdentity)
    RecallCore->>DB: embedTextForProject(intent) → vector
    alt embeddings available (rung 1)
        RecallCore->>DB: getRankingCandidates → cosine rank
    else FTS fallback (rung 3)
        RecallCore->>DB: searchSkillMemoryFts(sanitizedIntent)
    else flat fallback (rung 2/4)
        RecallCore->>DB: getSkillMemoryNotes ORDER BY recency x hit
    end
    RecallCore->>DB: bumpRecallCountByIds
    RecallCore->>HookHandlers: skill-memory XML block
    HookHandlers->>Model: append block to tool result

    Model->>DB: ctx_skill_note(skill, intent, kind, delta)
    DB->>DB: hash-dedup + cosine-dedup + insertSkillMemoryNote

    Historian->>DB: promoteSkillObservations(observations[])
    DB->>DB: "tier=global, project_identity=*, source_type=historian"

_{Reviews (8): Last reviewed commit: "fix(skill-memory): reject ctx_skill_note..." | Re-trigger Greptile}